Onboard and Authenticate User with Social Account Process

Content

• Overview
• OIDC: How it Works
• Adding Provider IDs to the Request URL
• Responsive Process Design
• Modifying User Details Returned by the Social Provider
• App Settings
• Onboarding Flow(s)
• Authentication Flow(s)
• Social Onboarding and/or Authentication User Journey
• API Walkthroughs
• Error Codes
• Revision History

Overview

This Process defines how an anonymous (or unauthenticated) user onboards and authenticates into ULM using a social media account. As one of the underlying components of ULM's Identity Management functionality, this Process supports the OIDC standard protocol for authentication and authorization between relying parties.

The Onboard & Authenticate User Process orchestrates two primary flows:

• Onboarding with Social Media flow: a new, anonymous user signs-up using their preferred social account. ULM Cloud uses details return from the social provider to create the User ID.
• Authentication with Social Media flow: an existing, anonymous user authenticates using their associated social account. The User ID already exists, and it the social account is already associated to the User ID.

This process is distinct from the Associate Social Account to User ID Process that can only be invoked by an existing, authenticated user who decides to associate their social account to their User ID.

OIDC: How it Works

Open ID Connect (OIDC) is an authentication layer which sits on top of the OAuth authorization framework. Where OAuth 2.0 allows a user to grant a third-party access to protected resources, OIDC extends that to allow the IdP (in this case ULM) to directly provide/request third-party information about the user.

A user who opts to onboard with a social account is first directed to the provider's website where they then sign into their account. The provider requires the user to explicitly share key information with ULM Cloud, and then redirects the user back to the client application where they first started their journey.

On the back end, ULM Cloud requests key user details (often known as "scopes") that will then be registered on the ULM User ID. The provider first returns a token to ULM, and a subsequent call to redeem that token results in user data that is added to the ULM User ID, including a contact channel and the provider's unique internal identifier for that social account. This information is used to create the new ULM User ID.

When an existing user opts to authenticate with an associated social account, and the provider is already associated to the User ID, the process queries the provider with a the unique identifier now stored on the User ID. ULM Cloud then authenticates the user once the provider confirms the internal identifier is still valid.

Third-party integrations allow users to share segments of their information from one website to another, without the need to expose their credentials.

Note: In this Process, the social provider federates user authentication to ULM Cloud. Similarly, ULM Cloud can also federate authentication to other third-party applications in order to enable single-sign on (SSO) with ULM Cloud as the authentication entry point. In other words, a user can authenticate into ULM using their preferred method, and then remain signed in once they navigate to provisioned relying parties. See the OIDC section in the MarketONE User Admin Guide for more details.

Adding Provider IDs to the Request URL

Like most Processes, this Process is initialized by the Process Start API. The Process Start API optionally consumes no payload, but you can add the required parameters upfront in the initial API request URL.

For example, in a normal invocation, the Process Star API consumes no payload:

<no body>

The Process then responds with a request for request for a supported providerID.

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "providerId": "String"
    },
    "stepName": "ProviderPrompt",
    "lastStep": false,
    "output": {
        "providers": [
                "linkedin",
                "google",
                "facebook",
                "apple"
        ]
    }
}

The UI would then need to provide that in the subsequent Process Step API.

However, the application can also simply invoke the Process with that providerId in the initial Process Start request URL:

• POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0?providerId=facebook
• POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0?providerId=google

As a best practice, adding the providerID to the request URL enables you to build your application to display social media badges on the sign-in and/or sign-up screens. The client can then invoke the provider-specific variation of the request when a user clicks on a provider-specific badge.

Responsive Process Design

This Process is responsive enough to account for edge cases and user error scenarios wherein a user mistakenly begins at one flow's starting point, but logistically needs to arrive at another flow's end result.

For example, a user who already owns a ULM User ID may mistakenly start from a client application UI's onboarding screen. Since the UI invokes the same Process from either flow's entry point, the communication between ULM Cloud and the social provider ensures that the user will arrive at the correct end point. See the below diagram for a better idea:

The result is a seamless flow that minimizes some of the friction that occurs from user errors.

Modifying User Details Returned by the Social Provider

When a user onboards with their social account, the social provider returns scopes that the user must confirm are valid. These scopes include an email address and/or mobile number. If the user confirms the details, then ULM creates the ULM User ID and registers the the email/mobile as both and authentication identifier and the user's primary contact channel. The user does not need verify this channel, as ULM Cloud implicitly trusts the provider. However, the Process also allows the user to optionally change the email/mobile returned by the provider.

If the user changes the email/mobile, the Process performs an additional check to see if that new email/mobile is already registered to an existing ULM User ID and, if a User ID is found, then prompts the user to supply a password to prove that they own the User ID. Once the user provides a valid password, the Process associates the social account to the existing User ID, and authenticates the user.

Alternatively, if the user-supplied email or mobile is not found in ULM, then the Process issues and and sends an action token to the user, in a verification message to that user-supplied contact channel. The Process then ends, and the user must then redeem that token with the GET session/token API to invoke Activate User Process.

Once invoked, the Activate User Process completes the onboarding (new ULM User ID is activated, email/mobile registered as AuthN ID), associates the social account, and authenticates the user into ULM.

App Settings

Certain aspects of the Process' behaviour are controlled by configurable application settings.

All app settings are set within the ULM Admin web application. System managers and administrators can consult the MarketONE User Admin UI User Guide.

Onboarding Flow(s)

The following tables describe the Process functionality at a high level, from an onboarding-oriented flow.

Authentication Flow(s)

The following table describes the Process functionality at a high level, for authentication scenarios.

Social Onboarding and/or Authentication User Journey

This diagram illustrates standard user journey(s) using the Onboard & Authenticate Use with Social Account Process.

Note: This diagram also includes the PUT session/token API (for verification resend), and the Activate User Process.

API Walkthroughs

The following section provides guided walkthroughs of the Onboard and Authenticate User with Social Account Process, including demonstrations of the various branching paths the Process can take during its execution.

Onboarding Scenario - No Matching User ID, User Confirms Provider Details

In this flow, a new, anonymous user onboards into ULM using their account with a trusted third-party social provider.

This flow also includes an alternate path wherein the user changes the email/mobile returned from the social provider.

Initial Request

The Process Start API initializes the Process:

<no body>

Response

The Process prompts the user to select a social provider, from a list of available options:

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "providerId": "String"
    },
    "stepName": "ProviderPrompt",
    "lastStep": false,
    "output": {
        "providers": [
                "linkedin",
                "google",
                "facebook",
                "apple"
        ]
    }
}

Response Parameters

Next Request: Choose Social Provider

The user enters their desired social provider, and the client passes that info to the Process with the Process Step API:

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "parameters": {
        "providerId": "facebook"
    }
}

Note: Facebook is the provider in this example, but the steps are the same regardless of the chosen provider.

Request Parameters

Response: Redirect URL to Social Provider

ULM responds with a redirect for the client to follow:

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "stepName": "CodePrompt",
    "lastStep": false,
    "output": {
        "requestUrl":"https://www.facebook.com/dialog/oauth?response_type=code&client_id=<redacted>
         &state=<redacted>&scope=public_profile%20email&redirect_uri=
         https%3A%2F%2Fidp-local.corp.amdocs.com%2Frest%2Fv70%2Fprocess%2Fstep"
    }
}

Response Parameters

Note: The client can skip this step if the social provider ID is provided in the initial Process Start request URL:

<no body>

This method is useful when social provider badges are displayed on a UI (for users to click and immediately begin the onboarding or authentication procedure).

Next Step: Redirect to Social Provider

Clients are expected to redirect to the URL provided in the requestUrl parameter. This URL redirects away from ULM Cloud and to the selected social provider (in this example, Facebook). Users are typically asked to authenticate to their social profile, then grant access for ULM to read basic information (their name, email address, etc). The social provider then redirects back to ULM Cloud with an authorization code, which ULM Cloud independently verifies with the social provider back end.

<no body>

Response: No User Found, Confirm Provider Details

The Process gets user details from the provide. No existing ULM user match is found, so the Process returns the provider details to the client for user confirmation:

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "confirm": "boolean",
        "lastName": "String",
        "firstName": "String",
        "phone": "String",
        "displayName": "String",
        "email": "String"
    },
    "stepName": "SocialUserInfoPrompt",
    "lastStep": false,
    "output": {
        "providerId": "facebook",
        "socialUserInfo": {
            "id": "1425242407805720",
            "email": "uxpsystemsmint@gmail.com",
            "firstName": "Bob",
            "lastName": "Jones"
        }
    }
}

Response Parameters

Final Request: Confirm and Complete

The user confirms the data to complete their profile:

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "parameters": {
        "confirm": "true",
        "lastName": "Jones",
        "firstName": "Bob",
        "email": "bobj@example.com",
        "displayName": "Bob Jones"
    }
}

Request Parameters

Response: Success

If the user confirms the information returned by the provider, ULM trusts the provider has verified the returned email/mobile. The Process completes its task and returns a 200 HTTP status code.

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "lastStep": true,
    "runtimeId": 5009,
    "userAuthenticated": true,
    "userId": 6013
}

The new User ID is created, activated, and associated to the social account. The user can now authenticate into ULM using this social account.

Response Parameters

Onboarding Scenario - No Matching User ID, User Changes Email/Mobile

This flow is the same as the above onboarding flow, except that the user does not confirm the email/mobile returned from the social provider. Instead, they change the email and/or mobile value(s) before hitting confirm.

Request: Submit Updated User Details

In this example, the user changes the email address returned by the provider:

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "parameters": {
        "confirm": "true",
        "lastName": "Jones",
        "firstName": "Bob",
        "email": "bobs_new_email@example.com",
        "displayName": "Bob Jones"
    }
}

Response: Process Complete, Prompt User to Verify Email/Mobile

If the new authN ID does not match an existing authN ID already assigned to an existing ULM User ID, the Process completes its task and returns a 200 HTTP status code. The Process also sends an action token to the user through email or SMS.

{
    "processId": "8f41d5cc-a4ab-45e9-9e3b-7f58a2ed183f",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "lastStep": true,
    "output": {
        "pkats": [
                "e82786ea-1e72-4880-b7e2-eb56031470e0"
            ]
        }
    },
    "runtimeId": 5009,
    "userId": 6018,
}

OTP Verification & Resend Verification

Any Process step that sends a ULM action token also returns a corresponding pkat to the client application. In order to enable OTP verification on the UI, the client must retain the pkat returned by the final Process step. The pkat, along with the user supplied OTP, is required for the GET /session/token?customToken={OTP}&pkat={pkat} API to invoke the Activate User Process.

In cases where the user is anonymous, the pkat is required if the application wants to provide a quick token resend option on the UI, using the PUT /session/token?pkat={pkat} API. This method applies to cases where the user is anonymous (i.e., they are not authenticated in ULM). However, if the user is currently authenticated in ULM, the client application can instead invoke the Resend Verification Process for this purpose.

Response Parameters

The user must verify their updated email/mobile value(s) before their ULM User ID is activated and fully associated to the social account. The Activate User Process will handle these updates once it is properly invoked and the relevant ULM action token is redeemed.

Onboard User Scenario - Existing User ID Found

In this flow, an anonymous user invokes the Process from an onboarding-oriented starting point, similar to the previous flows above. However, unlike in the previous flows, ULM Cloud detects that the email/mobile returned from the social provider is already registered as an authN ID on an existing ULM User ID. Therefore, the Process challenges the user for a password, to prove that the user actually owns the User ID.

Initial Request

The Process Start API initializes the Process:

<no body>

Response

The Process prompts the user to select a social provider, from a list of available options:

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "providerId": "String"
    },
    "stepName": "ProviderPrompt",
    "lastStep": false,
    "output": {
        "providers": [
                "linkedin",
                "google",
                "facebook",
                "apple"
        ]
    }
}

Response Parameters

Next Request: Choose Social Provider

The user selects their desired social provider, and the client passes that info to the Process with the Process Step API:

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "parameters": {
        "providerId": "facebook"
    }
}

Note: Facebook is the provider in this example, but the steps are the same regardless of the chosen provider.

Request Parameters

Response: Redirect URL to Social Provider

ULM responds with a redirect for the client to follow:

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "stepName": "CodePrompt",
    "lastStep": false,
    "output": {
        "requestUrl": "https://www.facebook.com/dialog/oauth?response_type=code&client_id=
         <redacted>&state=<redacted>&scope=public_profile%20email&redirect_uri=
         https%3A%2F%2Fidp-local.corp.amdocs.com%2Frest%2Fv70%2Fprocess%2Fstep"
    }
}

Response Parameters

Note: As noted above, the client can skip the provider selection step if the social provider ID is provided in the initial Process Start API request URL:

<no body>

This method is useful when social provider badges are displayed on a UI (for users to click and immediately begin the onboarding or authentication procedure).

Next Step: Redirect to Social Provider

Clients are expected to redirect to the URL provided in the previous response's requestUrl parameter. This URL redirects away from ULM Cloud and to the selected social provider (in this example, Facebook). Users are typically asked to authenticate to their social profile, then grant access for ULM to read basic information (their name, email address, etc). The social provider then redirects back to ULM Cloud with an authorization code, which ULM Cloud independently verifies with the social provider back end.

<no body>

Response: Existing User Found, Prompt for Password

The Process gets user details from the provider, and checks for a matching User ID. In this scenario, the the email/mobile returned from the provider is found on an existing User ID. The Process therefore prompts the user to provide a password and prove that they own the email/mobile (and by extension, the ULM User ID to which the email/mobile is registered):

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "credential": "String"
    },
    "stepName": "CredentialPrompt",
    "lastStep": false,
    "output": {
        "providerId":"facebook",
        "socialUserInfo": {
            "id": "1425242407805720",
            "email": "bob@example.com",
            "firstName": "Bob",
            "lastName": "Jones"
        }
    }
}

Response Parameters

Next Request: Provide Credential

The user provides their password, and the client passes it through the next Process Step API request:

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "parameters": {
        "credential": "Letm3inpl34se"
    }
}

Request Parameters

Response: Confirm Association

The Process authenticates the user, and prompts them to confirm that they want to complete the association between the social account and their ULM User ID.

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "confirm": "boolean"
    },
    "stepName": "ConfirmAssociation",
    "lastStep": false,
    "output": {
        "selectedUserId": 6013
        }
    }
}

Response Parameters

Final Request: Confirm Association

The user confirms the association, and the client passes this confirmation in its final request:

{
    "actionType": "com.uxpsystems.mint.framework.bpm.process.ManualInputStepAction",
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "parameters": {
        "confirm": "true"
    }
}

Request Parameters

Response: Success

The Process associates the social account to the User ID, authenticates the user, and returns a 200 HTTP status code.

{
    "actionType": "com.uxpsystems.mint.framework.bpm.process.AuthenticationCompleteStepAction",
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "lastStep": true,
    "runtimeId": 5009,
    "userId": 6013,
    "userAuthenticated": true
}

The user can now authenticate into ULM with their existing authN ID and password, or they can simply select to authenticate with the associated social account.

Response Parameters

Note: If the user does not confirm the association, they receive the same response that indicates successful authentication. However, the social account is not associated to their User ID. If they choose to attempt social login again, they will need to repeat this process flow.

Authentication Scenario

This flow enables an anonymous user to authenticate to ULM Cloud using a trusted third-party social provider. At the end of this flow, the user will be authenticated to ULM Cloud, dependent on a successful response from the chosen social provider.

This flow requires the user to have already associated a social account with their user profile, and they are selecting the same social provider to perform a subsequent authentication attempt.

Initial Request

Use the Start Process API to initiate the flow:

<no body>

Response

The API responds with a request to select a social provider, from a list provided.

{
    "processId": "c741ce95-0be3-4220-9532-692be317077c",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "providerId": "String"
    },
    "stepName": "ProviderPrompt",
    "lastStep": false,
    "output": {
        "providers": [
                "google",
                "facebook",
                "apple",
                "linkedIn"
        ]
    }
}

Response Parameters

Next Request: Select Social Provider

In this example, Facebook will be the selected social provider (although the steps are the same regardless of which provider is chosen). A response is crafted to indicate the selection:

{
    "processId": "c741ce95-0be3-4220-9532-692be317077c",
    "parameters": {
        "providerId": "facebook"
    }
}

Request Parameters

Response: Redirect URL to Social Provider

ULM responds with a redirect for clients to follow:

{
    "processId": "c741ce95-0be3-4220-9532-692be317077c",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "displayMessage": "Please input required information",
    "stepName": "CodePrompt",
    "lastStep": false,
    "output": {
        "requestUrl": "https://www.facebook.com/dialog/oauth?response_type=code&client_id=
         <redacted>&state=<redacted>&scope=public_profile%20email&redirect_uri=
         https%3A%2F%2Fidp-local.corp.amdocs.com%2Frest%2Fv70%2Fprocess%2Fstep"
    }
}

Response Parameters

Note: As noted above, the client can skip the provider selection step if the social provider ID is provided in the initial Process Start API request URL:

<no body>

This method is useful when social provider badges are displayed on a UI (for users to click and immediately begin the onboarding or authentication procedure).

Request: Redirect to Social Provider

Clients are expected to redirect to the URL provided in the previous response's requestUrl parameter. This URL redirects away from ULM Cloud and to the selected social provider (in this example, Facebook). Users are typically asked to authenticate to their social profile, then grant access for ULM to read basic information (their name, email address, etc). The social provider then redirects back to ULM Cloud with an authorization code, which ULM Cloud independently verifies with the social provider back end.

<no body>

The Process then authorizes the user and ends.

Response: Success

{
    "actionType": "com.uxpsystems.mint.framework.bpm.process.AuthenticationCompleteStepAction",
    "processId": "c741ce95-0be3-4220-9532-692be317077c",
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "lastStep": true,
    "runtimeId": 5010,
    "userId": 6013,
    "userAuthenticated" : true
}

Response Parameters

Error Scenario - Onboarding: Existing User Found, Invalid Password

If an existing User ID is found, the Process prompts for a password. If the user provides an invalid password, the Process responds with a HTTP 400 status code. The body includes a operationError array with the reason(s) as to what went wrong:

{
    "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
    "lastStep": false,
    "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
    "operationError": [
        {
            "code": "authentication-required",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "Bad credentials",
            "authorities": [
                {
                    "authority": "ROLE_ANONYMOUS"
                }
            ]
        }
    ],
    "stepName": "CredentialPrompt",
    "lastFailedStepAction": {
        "processId": "2a561555-e206-403b-aafc-0aa63a0dc3d9",
        "processName": "socialFederation.SocialMediaAssistedOnboarding.v1.0",
        "parameters": {
            "credential": "String"
        },
        "stepName": "CredentialPrompt",
        "output": {
            "providerId": "facebook",
            "socialUserInfo": {
                "id": "1425242407805720",
                "email": "bob@example.com",
                "firstName": "Bob",
                "lastName": "Jones"
            }
        }
    }
}

The Process also includes a lastStepFailedAction object that repeats the previous Process step's request. The user can re-attempt to submit a valid password.

Error Response Parameters

Error Codes

Below is a comprehensive list of potential error codes that may be returned during the execution of this Process.

Common Error Codes

Common Process Error Codes

Process-Specific Error Codes

Additional Notes

• ULM allows a user to have more than one social accounts associated to their User ID.
• ULM sends a notification message to the user confirming when they have successfully associated a social account.
• If the social provider returns an email address and mobile number, and the user changes the value for each, then they will need to verify each channel separately. The Process will issue and send two separate action tokens, and send them to each channel. Additionally, the Process returns two separate PKATs to to the client application.
• ULM currently supports account association with the following providers: Facebook, Google, Apple ID, and LinkedIn.

Revision History